home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Development Kits / MPW etc / MPW-GM / MPW / MPButtons / Documentation / User's Guide
Encoding:
Text File  |  1996-10-31  |  37.4 KB  |  954 lines  |  [TEXT/MPS ]

  1. #
  2. # MPButtons 2.2 User's Guide 
  3. # (describes release 2.2.0, November 1996)
  4. #
  5. # (c) 1993 JMP Soft, 1996 Soften
  6. #
  7.  
  8.  
  9. ————————---———————
  10. 1. About MPButtons 
  11. ————————---———————
  12.  MPButtons is a development utility providing a set of extensions to the MPW  
  13.  environment. Some of its features include:                                  
  14.  - searching for strings using a single click
  15.  - multiple smart clipboards with copy, paste, cut, swap and executable       
  16.    contents                                                                     
  17.  - tool for commenting and uncommenting a portion of source code
  18.  - function name popup, providing source overview and quick navigation
  19.  - searching and pasting items from Toolbox Assistant or THINK Reference 2.0
  20.  - API for adding custom functionality
  21.  
  22.  Each feature typically appears as a button at the top of an MPW window and   
  23.  can be used by mouse clicks or by using keyboard shortcuts.                  
  24.  
  25.  MPButtons provides:
  26.  - one always visible button — Selection
  27.  - up to seven optional Clipboard Buttons
  28.  - six optional Custom Buttons: Find, Comment, Function, Prototyper,          
  29.    Reference button and Script Button Example                                   
  30.  - you can find some other buttons in the More Buttons folder                                         
  31.  
  32.  MPButtons offers a large number of convenient functions. To help you to      
  33.  memorize most of them and to prevent your confusion an extensive quick       
  34.  reference is offered by balloon help. Complete description you can find in   
  35.  this file — table of contents is in the Mark menu. 
  36.  
  37.  Soon you will notice the natural distribution of power between three main    
  38.  MPButtons tools:
  39.  
  40.     1. Clipboards
  41.     2. Script Buttons
  42.     3. Code Buttons
  43.  
  44.  While the first tool is any time ready to hold and execute short sequence of 
  45.  MPW commands, the second tool enables to design and store (in the form of    
  46.  "button" with unique icon) more complex tasks, and the last tool is able to  
  47.  do any task - but it needs some effort, of course.                            
  48.  
  49.  This guide is organized according to buttons and actions you can do with each 
  50.  button. Typical paragraph begins for instance with the title "Option -       
  51.  Click" followed by description what will happen, when you option-click on    
  52.  a given button.                                                                
  53.  
  54.  
  55.  
  56. ——————————————---——
  57. 2. Selection Button
  58. ————————————---————
  59.  Selection Button is the first button from the left on the button bar with a  
  60.  selection icon (§).                                                              
  61.  
  62.  
  63. Click
  64.  Scrolls the contents of the window so that you can see cursor or beginning   
  65.  of the current selection (this is a shortcut to the Display Selection        
  66.  command in the MPW Find menu).                                                       
  67.  
  68.  
  69. Press
  70.  Popup menu with four items: Clips, Rebuild, About, Deinstall.
  71.  
  72. • Clips item has a submenu with numbers 0, 1,… 7; select the number of       
  73.   clipboards you want to use. Choosing zero will hide all the clipboard        
  74.   buttons. See the Clipboard Buttons mark for more information about using  
  75.   clipboard buttons. Each change in number of clipboards invokes Rebuild 
  76.   - see next.                                                          
  77.  
  78. • Rebuild command reloads Custom Buttons into the button bar according to 
  79.   current contents of the MPButtons folder. See the Custom Buttons mark. 
  80.  
  81. • About command shows the (surprise!) about box with contact.
  82.  
  83. • Deinstall gives you an alert. When you confirm, MPButtons will be          
  84.   permanently deinstalled from the MPW Shell.                                  
  85.  
  86.  
  87.  
  88.  
  89. ———————————---——————
  90. 3. Clipboard Buttons
  91. ———————————---——————
  92.  User-selectable number of buttons with a clipboard icon. You can change the  
  93.  number of Clipboard Buttons (including 0) by pressing the Selection Button   
  94.  and choosing from the Clips submenu. By reducing the number of clips the     
  95.  contents of all hiding Clipboard Buttons are lost.                           
  96.  
  97.  Each button offers its own clipboard, independent of all other MPButtons     
  98.  clipboards and the system clipboard. Each of MPButtons clipboard is global   
  99.  for all open MPW documents — its contents does not change by switching       
  100.  files. The contents of clipboards is saved (up to 10Kbytes each) in the      
  101.  MPButtons preferences file and will be available in your next MPW session.   
  102.  
  103.  In addition to copy, cut and paste functions you can execute commands stored 
  104.  in the MPButtons clipboards with the same results as if it was entered       
  105.  directly from the active MPW window. You can prepare different commands in   
  106.  different Clipboard Buttons. When you use some standard command sequences,   
  107.  try Script Buttons.                                                          
  108.  
  109.  The Clipboard Buttons and their respective functions rely heavily on the use 
  110.  of modifier combinations. The number of combinations used in mouse actions   
  111.  and shortcuts might seem confusing but there are a few rules, which can help 
  112.  you to remember the proper combination of modifier keys:                     
  113.  - Click pastes
  114.  - Control copies
  115.  - Option cuts
  116.  - Shift adds
  117.  - Command + n, where n is a numerical key, is a keyboard equivalent for      
  118.    Click (note that you can use the clipboards without actually clicking the    
  119.    respective button, by using a keyboard shortcut. See further description 
  120.    of keyboard shortcut assignment).                                            
  121.  
  122.  In the next detailed section MPButtons shortcuts are enclosed in parentheses.
  123.  The lower case letter 'n' represents a clipboard number (from 1 to 7) and a
  124.  respective numerical key on the keyboard.
  125.  
  126.  
  127. Click (Command + n) = Paste
  128.  Pastes the clipboard contents to the active document.
  129.  
  130.  If the clipboard is empty you will hear a beep. You can easily check the     
  131.  status of the clipboard: nonempty Clipboard Button has piece of paper in the 
  132.  clip on its icon.                                                            
  133.  
  134.  
  135. Control - Click (Control + Command + n) = Copy
  136.  Copies the current selection into the clipboard.
  137.  
  138.  If there is no selection, the clipboard is emptied and the button icon       
  139.  changes. This can be used for emptying the clipboard.                        
  140.  
  141.  
  142. Option - Click (Option + Command + n) = Cut
  143.  Cuts the current selection and replaces the clipboard contents with it.
  144.  
  145.  
  146. Shift - Control - Click (no shortcut) = Swap
  147.  Interchanges the clipboard contents and the current selection.
  148.  
  149.  
  150. Shift - Click (no shortcut) = Append
  151.  Appends the selection to the end of the clipboard contents.
  152.  
  153.  
  154. Control - Option - Click (Control + Option + Command + n) = Execute
  155.  Executes the MPW commands stored in the clipboard (cool!!). This way you can 
  156.  prepare several MPW script commands into your clipboards and execute them by 
  157.  Control - Option - Clicking on the respective Clipboard Button.              
  158.  
  159.  
  160. Control - Option - Command - Click  (no shortcut)
  161.  Executes MPW commands stored in the clipboard using Commando.
  162.  
  163.  
  164. Press
  165.  Shows the contents of the clipboard.
  166.  
  167.  
  168. Redefining the keyboard shortcut equivalents
  169.  
  170.  The MPButtons core defines four new sets of editor primitives for four main
  171.  clipboard actions. These primitives are named 
  172.  
  173.     MPBCopy1..MPBCopy7            (copy to clipboard 1..7)
  174.     MPBPaste1..MPBPaste7        (paste clipboard 1..7)
  175.     MPBCut1..MPBCut7            (cut to clipboard 1..7)
  176.     MPBDo1..MPBDo7                (execute clipboard 1..7)
  177.  
  178.  This allows you to modify predefined shortcuts using the SetKey command in a 
  179.  way, consistent with the MPW shell. For instance after setting 
  180.  
  181.     SetKey Command-Q MPBPaste3
  182.  
  183.  you can paste the contents of the 3rd clipboard using the shortcut 
  184.  Command - Q (by the way, this example is not a very smart shortcut selection).         
  185.  
  186.  
  187.  
  188.  
  189. ———---————————
  190. 4. Find Button
  191. ——————---—————
  192.  Find Button is a Custom Code Button (see the Custom Buttons mark) with an    
  193.  eye icon. It offers an extension to the original MPW Find functions.         
  194.  MPButtons shares the find buffer with MPW — you can take advantages of the   
  195.  MPW find with all its features and shortcuts.                                
  196.  
  197.  
  198. Click
  199.  Copies the current selection into the find buffer (if there is any           
  200.  selection) and searches the current file for the contents of the find        
  201.  buffer. Clicking the upper part of the button will search backward, the      
  202.  lower part searches forward.                                                 
  203.  
  204.  If there is no selection the MPButtons searches for the current find buffer  
  205.  contents. If the find buffer is empty the Find dialog box is displayed.      
  206.  
  207.  Clicking the lower part of the Find Button is functionally equivalent to the 
  208.  MPW shortcut Command-H (respectively Command-G if there is no selection) and 
  209.  clicking the upper part of the Find Button is functionally equivalent to the 
  210.  MPW shortcut Shift-Command-H (respectively Shift-Command-G if there is no    
  211.  selection).                                                                   
  212.  
  213.  
  214. Option-click
  215.  The same as Click but does not modify the find buffer: searches the current
  216.  file for the contents of the find buffer regardless to the current selection.
  217.  This is a faster equivalent to first deselecting the current selection and
  218.  then clicking the Find Button (or pressing the MPW Command-G shortcut). Once
  219.  again, the upper part of the button searches backward, the lower part searches
  220.  forward.
  221.  
  222.  
  223. Command-click (Option + Command + H forward or Shift + Option + Command + H backward)
  224.  The same as click (searches for selection) but preserves the current         
  225.  selection. The string that is found is hilited for a moment and stays        
  226.  visible in the window. The current selection remains unchanged, you can      
  227.  return to it by clicking on the Selection button.                     
  228.  
  229.  
  230. Option-Command-click (Option + Command + G forward or Shift + Option + Command + G backward)
  231.  The same as Option-click (searches for buffer contents) but preserves the    
  232.  current selection. The string that is found is hilited for a moment and      
  233.  stays visible in the window. The current selection remains unchanged, you    
  234.  can return to it by clicking on the Selection button.                
  235.  
  236.  
  237. Press
  238.  Displays the popup menu with the last ten searched strings. If you select   
  239.  one of them it replaces the find buffer and is searched for. Also, after you 
  240.  display the popup next time you can see that this selected string became    
  241.  the first item (the first item indicates the latest searched string).        
  242.  
  243.  
  244. Control-press
  245.  Shows the string that could be searched for by immediately following click;  
  246.  no search is performed.                                                      
  247.  
  248.  If there is a nonempty selection it is shown. Now you can alter the find     
  249.  buffer contents: if you release mouse inside the Find Button the current      
  250.  selection replaces the find buffer. If you release mouse outside the Find    
  251.  button the find buffer contents remains unchanged.                            
  252.  
  253.  If there is no selection the find buffer contents is shown. If the find       
  254.  buffer is empty you can see a warning message.                                            
  255.  
  256.  
  257. Option-Control-press
  258.  Shows the find buffer contents regardless to the current selection. If the    
  259.  find buffer is empty you can see a warning message.                                       
  260.  
  261.  
  262.  
  263. ———-—————————————
  264. 5. Comment Button
  265. ————-————————————
  266.  Comment Button is a Custom Code Button (see the Custom Buttons mark) with  
  267.  one string of comment characters in the button icon (#, ;, /*, // or {}). It   
  268.  helps to comment or uncomment a selection. Can be used for disabling parts   
  269.  of source code and for formatting plain text into multiple line comments.    
  270.  
  271.  The comment characters in the Comment Button icon changes, depending on    
  272.  the type of the source file in the active window (can be changed         
  273.  manually, see the mark Comment types).                                                               
  274.  
  275.  
  276. Click (Control + Command + C)
  277.  Comments or uncomments the current selection. If the selection contains at 
  278.  least one newline character it expands to whole lines. Uncommenting takes 
  279.  effect if the selection starts with the opening sequence of comment 
  280.  characters of given type (see the mark Comment types). 
  281.  
  282.  In C and Pascal comment types MPButtons preserves pairing of open and close  
  283.  comment characters. When you comment a selection containing original         
  284.  comments, they change into nested comments using bullets (•) and angle       
  285.  bracket characters and can be therefore distinguished from MPButtons         
  286.  comments. Example in Pascal:                                                 
  287.  
  288. { if w in ['a','e','i','y','o','u'] then <•vowels•>}
  289. { begin}
  290. {    inc( nw);}
  291. {    next( w)}
  292. { end;}
  293.  
  294.  After uncommenting you'll get the original comments:
  295.  
  296.  if w in ['a','e','i','y','o','u'] then {vowels}
  297.  begin
  298.     inc( nw);
  299.     next( w)
  300.  end;
  301.  
  302.  MPButtons will not comment a selection with incomplete comments.
  303.  
  304.  
  305. Shift - Click
  306.  Extends the current selection to whole lines and closes it into IFDEF/ENDIF 
  307.  lines. Only for C, C++ and Pascal comment types. Example in Pascal: 
  308.  
  309.  {$IFC DEBUG}
  310.  if w in ['a','e','i','y','o','u'] then
  311.  begin
  312.     inc( nw);
  313.     next( w)
  314.  end;
  315.  {$ENDC}
  316.  
  317.  The default ifdef string is set to DEBUG and can be freely modified using 
  318.  "Set ifdef §" command — see the mark Comment types. 
  319.     
  320.     
  321. Command - Click
  322. # Helps to format multiline comments. This and next four paragraphs show results
  323. # of command-clicks on the Comment button with all possible comment types (see
  324. # the mark Comment types on how to select the comment type).
  325.  
  326. ; The function expands the selection to whole lines, strips comment signs,
  327. ; breaks the selection like a typical text processor does, and finally closes
  328. ; every line separately into comment signs. • Warning • All comment characters
  329. ; of chosen type are stripped including those not used as comment signs.
  330.  
  331. /* The whole selection is expected to be only one paragraph. If your comment  */
  332. /* contains more then one paragraph, you need to break every paragraph        */
  333. /* separately.                                                                */
  334.  
  335. // In C and Pascal comment types spaces are inserted between the last character
  336. // of a line and the closing sequence of comment characters. Right margin is set
  337. // to column 80. (Monospaced font like Monaco is expected.)
  338.  
  339. { By the way, this file was finally formatted by command-click and click       }
  340. { sequence on each selected paragraph. Command-click broke a paragraph and     }
  341. { next click striped comment signs.                                            }
  342.  
  343.  
  344. Press
  345.  Pressing the Comment Button presents a popup menu with comment types (MPW, 
  346.  Assembler, C, C++ and Pascal). The last item is "Set ifdef §" command, see   
  347.  later.                                                                       
  348.  
  349.  No commenting or formatting is performed as a result of pressing the
  350.  comment button. 
  351.  
  352.  The active comment type (that is marked in popup menu) can be overridden by
  353.  choosing another type from the popup menu. The type of commenting changes not
  354.  only the comment characters, but it also affects the ifdef and formatting
  355.  features. Type of commenting is a local feature in each MPW file and is saved
  356.  with the file.
  357.  
  358.  • Note •  By default, the commenter picks the type of commenting depending on 
  359.  the source file name suffix. In the button's resources of type 'SUFX' there  
  360.  are defined file name suffixes for specific languages. The TMPL resource is  
  361.  provided, so you can easily add your own suffix or just modify an existing   
  362.  one using your favourite resource editor.                                    
  363.  Java source files have assigned the C style of comments. MagicCap sources    
  364.  have assigned the C++ style of comments.                                     
  365.  
  366.  To change the ifdef string:
  367.  (1) type the string in an active window and select it,
  368.  (2) press the Comment button and choose the "Set ifdef §" command.
  369.  From now on every shift-click will use the new ifdef string.
  370.  
  371.  
  372.  
  373.  
  374. ——————————————————
  375. 6. Function Button
  376. ——————————————————
  377.  Function Button is a Custom Code Button (see the Custom Buttons mark) with   
  378.  a small popup menu icon. This button is designed to help you navigate through  
  379.  the source files. It displays a popup menu of functions in the current       
  380.  document. Currently, the following file types are supported:
  381.  
  382.     • C/C++
  383.     • MagicCap
  384.     • Pascal
  385.     • FORTRAN
  386.     • Assembler (68k, PPC)
  387.     • Java
  388.  
  389.  Selecting an item from the popup menu will select the appropriate function   
  390.  name. It also allows to step forward or backward over function names. In
  391.  addition to displaying functions, the Function Button displays various
  392.  other items, such as structs, typedefs, enums and classes in C++, etc. 
  393.  
  394.  
  395. Click (Control+Command+F forward and Shift+Control+Command+F backward)
  396.  Moves to the previous/next function in the source file from the current      
  397.  cursor position. If there are no more functions in the chosen direction,     
  398.  Function Button beeps. The button is split into two halves to enable the     
  399.  backward/forward browsing.                                                  
  400.  
  401.  
  402. Command - Click
  403.  Moves to the previous/next function in the source file but preserves the     
  404.  current selection. Then you can go back using the Selection button. This     
  405.  feature is useful when you want just to have a quick look at the             
  406.  previous/next function without changing the selection.                       
  407.  
  408.  
  409. Option - Click (Control + Option + Command + F)
  410.  Searches the file for the current selection used as a function definition. 
  411.  Beeps if not successful. 
  412.  
  413.  
  414. Press 
  415.  Displays a popup menu of functions in the current file. In the popup menu,   
  416.  the check mark indicates that cursor (or selection start) is in the marked   
  417.  function. If the current document contains no functions a popup menu with a  
  418.  dimmed "no function definitions" item appears. The suffix in the name of the 
  419.  document determines which language will be used for searching for functions  
  420.  in the document. See following section on information on how to configure    
  421.  it.
  422.  When encountering overloaded functions in C or C++, the function popup
  423.  displays the functions parameters to help distinguish between different
  424.  overloaded functions using the same function name.
  425.                                                     
  426.  
  427. Shift - Press
  428.  When using the Shift modifier, some additional information will appear in    
  429.  the function popup:                                   
  430.  
  431.     • Function arguments (in abbreviated form) 
  432.     • Function prototypes 
  433.     • Struct, enum, union, class and type definitions
  434.  
  435.  
  436. Control - Press
  437.  While pressing the Control modifier the class member functions are           
  438.  displayed.
  439.  Note: This is valid only in C++ and MagicCap files.                                  
  440.  
  441.  
  442. Control - Option - Press
  443.  The same as Control-Press but the popup menu is sorted alphabetically.           
  444.  
  445.  
  446. Option - Press
  447.  While pressing the Option modifier the popup menu is sorted alphabetically.  
  448.  
  449.  
  450. Command - Press
  451.  If you select a function name in the popup menu while pressing the Command   
  452.  key the function is displayed but not selected (the current selection        
  453.  position remains unchanged). Then you can go back using the Selection        
  454.  button. This feature is useful when you want just to have a quick look at    
  455.  the specific function without changing the selection.                        
  456.  
  457.  
  458.  
  459.  Configuring the Function Button
  460. ———————————————————————————————
  461.  The language used for looking for functions in the current document is       
  462.  derived from the suffix of the name of the document. The resources of type   
  463.  'SUFX' in the Function button file contain the mapping information used to   
  464.  determine a specific language. You can append your own filename suffixes to  
  465.  these resources.                                                             
  466.  
  467.  
  468.  
  469. —————————————
  470. 7. Prototyper
  471. —————————————
  472.  
  473.  In addition to usual prototyping of C functions, the prototyper provides a   
  474.  number of functions that ease C++ coding.                                    
  475.  
  476. Feature overview:
  477. -----------------
  478.  
  479.  Prototyping - generating C and C++ function prototypes.                      
  480.  Inverse prototyping - generating empty functions from function prototypes or 
  481.  C++ classes.                                                                 
  482.  Inline extraction - removes inline function code from inside C++ classes and 
  483.  lets the user paste the inlines outside the class.                           
  484.  
  485.  
  486. C function prototyping:
  487. -----------------------
  488.  
  489. select:
  490.  
  491. void
  492. a(int b)
  493.         {
  494.         int c = b;
  495.         }
  496.  
  497. click prototyper button, get:
  498.  
  499. extern void a(int b);
  500.  
  501.  Select one or more functions and click the prototyper button. If the         
  502.  selected functions are valid, you will notice that the prototyper button     
  503.  will change to a loaded state. You can select any part of a function to      
  504.  include it's prototype.                                                      
  505.  
  506.  Pressing on the button will display the prototypes waiting to be pasted into 
  507.  your source file.                                                            
  508.  
  509.  Control clicking will clear out the prototyper clipboard and will let your   
  510.  generate new prototypes.                                                     
  511.  
  512.  Clicking on the prototyper button will paste the prototypes from the buttons 
  513.  clipboard into the current selection.                                        
  514.  
  515.  The prototyper only for static functions. However, if you press the option   
  516.  key while clicking the prototyper button, prototypes of static functions     
  517.  will also be generated. If you only select static functions and do not hold  
  518.  down the option button while pressing the prototyper button, the button will 
  519.  remain empty.                                                                
  520.  
  521.  
  522. C++ function prototyping:
  523. -------------------------
  524.  
  525. select:
  526.  
  527. void
  528. SomeClass::SomeMemberFunction(int a, void b)
  529.         {
  530.         int c = a;
  531.         b = 0;
  532.         }
  533.  
  534. click prototyper button, get:
  535.  
  536.         void SomeMemberFunction(int a, void b);
  537.  
  538.  
  539.  When prototyping C++ member functions the resulting prototype is indented by 
  540.  a single tab, ready to be pasted into the corresponding C++ class.           
  541.  
  542.  
  543. Appending prototypes:
  544. ---------------------
  545.  shift-click
  546.  
  547.  If your prototyper buttons contains prototypes that are ready to be pasted,  
  548.  you can add more prototypes to the same batch by selecting functions and     
  549.  shift clicking the prototyper button. The prototyper will now contain the    
  550.  previous prototypes as well as new ones you just added. Clicking on the      
  551.  prototyper button will paste them all at once into the current selection.    
  552.  
  553.  
  554. Inverse prototyping:
  555. --------------------
  556.  
  557. select:
  558.  
  559. extern void a(int b);
  560.  
  561. click prototyper button, get:
  562.  
  563. void
  564. a(int b)
  565.         {
  566.         }
  567.  
  568.  If you select function prototypes and click the button the prototyper will   
  569.  generate inverse prototypes - empty functions ready to be filled out with    
  570.  code.                                                                        
  571.  
  572.  
  573. Inverse C++ function prototyping:
  574. ---------------------------------
  575.  
  576. select:
  577.  
  578. class a
  579.         {
  580.   public:
  581.         virtual int a(int i);
  582.         void a(int i, int j) const;
  583.         short b(int i);
  584.         };
  585.  
  586.  click prototyper button, and the prototyper clipboard contains this:         
  587.  
  588. inline int 
  589. a::a(int i)
  590.         {
  591.         }
  592.  
  593. inline void
  594. a::a(int i, int j) const
  595.         {
  596.         }
  597.  
  598. inline short 
  599. a::b(int i)
  600.         {
  601.         }
  602.  
  603.  Inverse prototyping is very useful for C++ programming where it's common to  
  604.  first design class definitions and then write the actual code. When you are  
  605.  done with the class definition, you select it, click the prototyper button,  
  606.  paste the prototypes into your source file and fill out the code. This would 
  607.  otherwise take multiple copy-paste steps and editing.                        
  608.  
  609.  The prototyper appends inline to each of the inverse prototypes, if you want 
  610.  a give function to be out of line, you need to remove the directive.         
  611.  
  612.  By default the prototyper will not generate inverse prototypes for, pure     
  613.  virtual functions and functions that are inlined inside the class            
  614.  definition, since it is likely that you will not be adding any code to       
  615.  these. If you want to also generate inverse inlines for two above cases,     
  616.  hold down the option key while pressing the prototyper button.               
  617.  
  618.  Generating inverse prototypes for C++ templates:                             
  619.  
  620. select this:
  621.  
  622. template<class StringKey, class Value>
  623. class StringKeyEntry: public StringKey
  624.         {
  625.   public:
  626.         Value value;
  627.         void setValue(const Value &v)
  628.         int compare(const char *k) const;
  629.         };
  630.  
  631.  click the prototyper and get this:                                           
  632.  
  633. template<class StringKey, class Value>
  634. void 
  635. StringKeyEntry<StringKey, Value>::setValue(const Value &v)
  636.         {
  637.         }
  638.  
  639. template<class StringKey, class Value>
  640. int 
  641. StringKeyEntry<StringKey, Value>::compare(const char *k) const
  642.         {
  643.         }
  644.  
  645.  Two mouse clicks generate the equivalent of a tedious and error-prone        
  646.  copy-paste-edit sequence.                                                    
  647.  
  648.  
  649. Inline extraction:
  650. ------------------
  651.  
  652.  select this:                                                                 
  653.  
  654. class a : public b
  655.         {
  656.   public:
  657.         a(int i) : b(i), x(i) { y = 0; }
  658.   private:
  659.         int x, y;
  660.         };
  661.  
  662.  shift-option click the prototyper, the prototyper clipboard contains this:   
  663.  
  664. inline 
  665. a::a(int i)
  666.         :       b(i),
  667.                 x(i)
  668.         {
  669.         y = 0;
  670.         }
  671.  
  672.  When selecting a C++ class with inlines the generated prototypes contain the 
  673.  inline code.                                                                 
  674.  
  675.  By holding down command while clicking the prototyper button, inline         
  676.  functions are also removed from the class definition:                        
  677.  
  678. class a : public b
  679.         {
  680.   public:
  681.         a(int i) : b(i), x(i) { y = 0; }
  682.   private:
  683.         int x, y;
  684.         };
  685.  
  686.  shift-option click the prototyper, the class becomes:                        
  687.  
  688. class a : public b
  689.         {
  690.   public:
  691.         a(int i);
  692.   private:
  693.         int x, y;
  694.         };
  695.  
  696.  and the prototyper clipboard contains this:                                  
  697.  
  698. inline 
  699. a::a(int i)
  700.         :       b(i),
  701.                 x(i)
  702.         {
  703.         y = 0;
  704.         }
  705.  
  706.  This feature is useful for formatting existing C++ code to your taste.       
  707.  Including inlines into the class definition is a little faster to type than  
  708.  writing separate inline functions but may make the class hard to read. Using 
  709.  the inline extraction feature you can write the class fast and then extract  
  710.  the inlines and paste them separately.                                       
  711.  
  712.  
  713. Modifier key overview:
  714. ----------------------
  715.  
  716.  control    - clear prototyper clipboard                                         
  717.  option        - prototype everything, including static functions, pure virtual      
  718.                  functions, inline functions in class definition                              
  719.  command    - extract inlines                                                    
  720.  shift        - append new prototypes to prototyper clipboard                        
  721.  
  722.  
  723.  
  724. ———---—————————————
  725. 8. Reference Button
  726. ——————---——————————
  727.  This is a Custom Code Button with spectacles icon. Searches for the          
  728.  reference in Toolbox Assistant or THINK Reference 2.0 (let's call the        
  729.  selected application generally 'reference application') and optionally       
  730.  pastes the template. You have to have a copy of reference application (or    
  731.  just its alias) installed on the same volume as your MPW Shell is running.   
  732.  The reference application will be automatically launched by the button.      
  733.  
  734.  
  735. Click (Command + minus)
  736.  Searches for the selected item in the reference application. If there is no  
  737.  selection and cursor is in a word then this word is selected automatically.  
  738.  The reference application is activated and the appropriate reference is      
  739.  displayed. If the reference application can't be found or can't be run or    
  740.  the selected item has no reference the button beeps.                         
  741.  
  742.  
  743. Option - Click (Option - Command - minus)
  744.  Searches for the selected item in the reference application and replaces the 
  745.  selection by the template found for this item. See Click above for the       
  746.  button behavior.                                                             
  747.  
  748.  
  749. Press
  750.  Pressing the Reference Button presents a popup menu for selecting the        
  751.  reference application. You can select Toolbox Assistant or THINK Reference.  
  752.  
  753.  
  754.  
  755. ———---———————————
  756. 9. Custom Buttons
  757. ——————---————————
  758.  There are two kinds of Custom Buttons - Script Buttons and Code Buttons.     
  759.  Script Buttons contain MPW scripts and can have some additional features.    
  760.  Code Buttons are extensions which communicate with the MPButtons core        
  761.  through a predefined API. Each Custom Button can have 1, 2, or 4 sections    
  762.  with different purposes.                                                     
  763.  
  764.  Custom Button can be easily added/removed to/from the MPButtons bar by       
  765.  adding/removing the button file with puzzle icon to/from "MPButtons" folder   
  766.  (inside your "{ShellDirectory}" folder) and “rebuilding” the button bar.                                                
  767.  
  768.  When MPW Shell is launched, or when the Rebuild command (from the Selection     
  769.  button) is invoked, or when you change the number of clipboards, MPButtons     
  770.  core looks for files with type 'TEXT' (Script Buttons) or type 'CBtn' with   
  771.  creator 'MPS ' (Code Buttons) in "MPButtons" folder. When MPButtons finds a    
  772.  button, it attempts to install it into the MPButtons bar. If installation is 
  773.  successful, the button appears in the bar and is ready to use.               
  774.  
  775.  • Note •  Custom Buttons are ordered alphabetically in the button bar. You    
  776.  can rearrange the position of each Custom Button by preceding the name with  
  777.  a digit: '1Function', '2Comment', etc.                              
  778.  
  779.  
  780.  
  781. 9.1 Script Buttons
  782. ————----——————————
  783.  Script Buttons are in fact MPW scripts with some optional features. For      
  784.  occasion command executing see Clipboard Buttons; on the other side more      
  785.  power you can get from Code Buttons.                                         
  786.  
  787.  Every script file can be used as a Script Button. Make sure the file is an   
  788.  MPW script file, move it to the MPButtons folder and rebuild MPButtons (see  
  789.  the mark Selection Button - Rebuild).                                        
  790.  
  791.  When you click on the new installed button in the MPButtons bar (it has a 
  792.  default icon), the appropriate script is executed. When you press the 
  793.  button, you'll see the content of the script. 
  794.  
  795.  A Script Button may contain lines with '#MPB' keyword at the beginning - these
  796.  lines are skipped in a normal script since they start with the '#' character.
  797.  These lines have special meaning for the MPButtons core. They indicate that a
  798.  special command follows. This command can be one of the following:
  799.  #MPB AREA <number 0-3>
  800.  #MPB MODIFS <modifier combination>
  801.  #MPB SHORTCUT <SetKey-like key combination>
  802.  
  803.  
  804. #MPB AREA <number 0-3>
  805.  This command divides the script into two or four sections. Each section is
  806.  executed when appropriate section of the button is clicked. If the section of
  807.  a button is pressed, the content of that area in the script is shown. "Areas"
  808.  are identified the following way:
  809.  
  810.     +---+    +---+    +-+-+
  811.     |   |    | 0 |   |0|1|
  812.     | 0 |    +---+    +-+-+
  813.     |   |   | 1 |   |2|3|
  814.     +---+    +---+    +-+-+
  815.     
  816.  AREA commands with a number greater than 3 just mark the end of the previous
  817.  area command, but are not used for identifying an area. The button is divided
  818.  according to the highest section number in the text, i.e. if the button text
  819.  contains only one area command AREA 3, the button will be still divided into
  820.  four parts, although only the bottom-right part will have an "action" on it.
  821.  
  822.  When no MPB AREA is defined, whole text is supposed to be in area 0.
  823.  
  824.  
  825. #MPB MODIFS <modifier combination>
  826.  This command begins the section of each button area which will be executed
  827.  when you click on the appropriate button section with specified modifiers. The
  828.  button section which is located between the AREA command and the first MODIFS
  829.  command will be executed when no modifiers are pressed.
  830.  
  831.  
  832. #MPB SHORTCUT <SetKey-like key combination>
  833.  This command has a slightly different behavior than the previous ones. It    
  834.  marks a global position in the text (no matter in which section it is). Text 
  835.  following this command up to the next #MPB command will be executed when you 
  836.  press the defined shortcut. When you place the same SHORTCUT command at      
  837.  several locations in the script, the last one will be used when you press    
  838.  the shortcut. The notation for describing the shortcuts is                   
  839.  "hyphen-divided-modifiers-and-key" (i.e. "Command-Control-Option-Q").        
  840.  
  841.  #MPB SHORTCUT lines are ignored by the AREA and MODIFS commands. You can     
  842.  define the SHORTCUT command in the middle of the AREA and that area will     
  843.  continue after that line. If you define the SHORTCUT just after the MODIFS   
  844.  command, the following action will be invoked when you click on the button   
  845.  with the defined modifiers and ALSO when you press the defined shortcut.     
  846.  
  847.  
  848.  The #MPB are designed to be flexible and it's the users responsibility to    
  849.  use them in a reasonable way.                                                
  850.  
  851.  See the files "Script Button Example" and "Funny Script Button" to learn how 
  852.  Script Buttons work and how to use the #MPB commands.                        
  853.  
  854.  
  855. How to edit Script Buttons
  856.  There is a convenient shortcut: when you click on a Script Button with all
  857.  modifiers pressed (Shift-Control-Option-Command-click), the respective script
  858.  file is opened to the MPW Shell environment. You can then edit the script.
  859.  When you are done with editing, save the file and select Rebuild from the
  860.  Selection Button, to make the changes effective.
  861.  
  862.  
  863. Assigning custom icons to Script Buttons
  864.  By placing a script file into the MPButtons folder and Rebuilding the
  865.  MPButtons bar the script is displayed as a Script Button with a default icon.
  866.  You can customize this icon so that you can distinguish the individual script
  867.  buttons.
  868.  
  869.  To assign your own icon to a Script Button, open the script file in your     
  870.  resource editor and insert the icons for the 
  871.  
  872.  released button state   into the icon family resources with the number 10000 
  873.  pressed state           into the icon family resources with the number 10001 
  874.  
  875.  in the Script Button's resource fork. The icon family contains resources of  
  876.  type                                                                         
  877.     icl8    for eight-bit color,
  878.     icl4    for four-bit color,
  879.     ICN#    for black & white.
  880.  
  881.  Do not forget to specify the mask too. The fastest way is to copy the whole  
  882.  icon family from any Script Button with custom icon. As a start try to use   
  883.  the "Funny Script Button" from More Buttons folder.                          
  884.  
  885.  During the initialization time the MPButtons core looks for these resources  
  886.  in each button. When it finds them, it will use them as the button icon,     
  887.  otherwise it will use the default icon. See the icons of the buttons you get 
  888.  along with MPButtons to see how to design an icon for a button with          
  889.  sections. Notice that a button with sections will have its respective        
  890.  depressed icon designed as if all the button sections were depressed at the  
  891.  same time.                                                                   
  892.  
  893.  
  894. Assigning balloon help to Script Buttons
  895.  Each button including a Script Button can have balloon help. To assign       
  896.  balloon help to a Script Button, put the resource 'STR#' 10000 into the      
  897.  button's resource fork. Each string in that resource will be used for one    
  898.  section balloon, corresponding to one #MPB AREA n command (see Script Button 
  899.  Example).                                                                    
  900.  
  901.  
  902.  
  903. 9.2 Code Buttons
  904. ————----————————
  905.  Code Buttons are special buttons, communicating with the MPButtons core with 
  906.  a special plug-in API, similar to that of QuarkXTensions, Adobe Illustrator  
  907.  5.0 plugins, etc. You can design your own Code Button when neither           
  908.  executable Clipboard Buttons nor Script Buttons satisfy your needs.        
  909.  
  910.  The API features include:
  911.  - init, exit, events, open document, close document, modified document, redraw,
  912.    click and press input actions
  913.  - decision which actions to get                             
  914.  - the ability to be called repeatedly
  915.  - text editing tools 
  916.  - file handling tools
  917.  - button rectangle coordinates           
  918.  
  919.  There are five Code Buttons that come along with MPButtons - Find, Comment,  
  920.  Function, Prototyper and Reference. Each of them was implemented as a        
  921.  plugin, using the API. You can find some additional code buttons in the More 
  922.  Buttons folder.                                                              
  923.  
  924.  The API (along with a sample source code) is available to developers who     
  925.  want to create their own Code Buttons. See following contacts.               
  926.  
  927.  
  928.  
  929.  
  930. ———---—————
  931. 10. Contacts
  932. ——————---——
  933.  Soften
  934.  Na písku 131
  935.  154 00 Praha 5
  936.  Czech Republic
  937.  
  938.  E-mail: buttons@login.cz
  939.  Web:    http://www.soften.cz
  940.  
  941.  Fax:     (+42 2) 556 496 or (+42 2) 651 3618    (both 7:00am - 7:00pm GMT)
  942.  
  943.  
  944.  Your feedback is welcome!
  945.  
  946. —————————————————————————————————————————————————————————————————————————————
  947. JMP Soft was the former name of our company (since 1993 to 1996).
  948. Adobe Illustrator is a trademark of Adobe Systems, Inc.
  949. MPButtons is a trademark of Soften.
  950. MPW is a registered trademark of Apple Computer, Inc.
  951. QuarkXTension is a trademark of Quark, Inc.
  952. THINK Reference is a trademark of Symantec Corporation.
  953.  
  954.